<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Venice  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
  </head>
  <body>
    <a title="Venice  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">Venice Docs</a> (100% documented)</p>
        <p class="header-right"><a href="https://github.com/Zewo/Venice"><img src="img/gh.png"/>View on GitHub</a></p>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">Venice Reference</a>
        <img id="carat" src="img/carat.png" />
        Venice  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Coroutines.html">Coroutines</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/Coroutine.html">Coroutine</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/Coroutine/Group.html">– Group</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Channels.html">Channels</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/Channel.html">Channel</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/Channel.html#/s:CC6Venice7Channel7Sending">– Sending</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/Channel.html#/s:CC6Venice7Channel9Receiving">– Receiving</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="File Descriptors.html">File Descriptors</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/FileDescriptor.html">FileDescriptor</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/FileDescriptor/PollEvent.html">– PollEvent</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Time.html">Time</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/Duration.html">Duration</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/Deadline.html">Deadline</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Int.html">Int</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Errors.html">Errors</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Enums/VeniceError.html">VeniceError</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <h1 id='venice' class='heading'>Venice</h1>

<p><a href="https://swift.org"><img src="https://img.shields.io/badge/Swift-3.1-orange.svg?style=flat" alt="Swift"></a>
<a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat" alt="License"></a>
<a href="http://slack.zewo.io"><img src="https://zewo-slackin.herokuapp.com/badge.svg" alt="Slack"></a>
<a href="https://travis-ci.org/Zewo/Venice"><img src="https://travis-ci.org/Zewo/Venice.svg?branch=master" alt="Travis"></a>
<a href="https://codecov.io/gh/Zewo/Venice"><img src="https://codecov.io/gh/Zewo/Venice/branch/master/graph/badge.svg" alt="Codecov"></a>
<a href="https://codebeat.co/projects/github-com-zewo-venice"><img src="https://codebeat.co/badges/bd12fff5-d499-4636-83e6-d4edf89585c5" alt="Codebeat"></a>
<a href="http://zewo.github.io/Venice"><img src="http://zewo.github.io/Venice/badge.svg" alt="Documentation"></a></p>

<p><strong>Venice</strong> provides <a href="http://libdill.org//structured-concurrency.html">structured concurrency</a> and <a href="https://en.wikipedia.org/wiki/Communicating_sequential_processes">CSP</a> for <strong>Swift</strong>.</p>
<h2 id='features' class='heading'>Features</h2>

<ul>
<li>Coroutines</li>
<li>Coroutine cancelation</li>
<li>Coroutine groups</li>
<li>Channels</li>
<li>Receive-only channels</li>
<li>Send-only channels</li>
<li>File descriptor polling</li>
</ul>

<p><strong>Venice</strong> wraps a fork of the C library <a href="https://github.com/sustrik/libdill">libdill</a>.</p>
<h2 id='installation' class='heading'>Installation</h2>

<ul>
<li>Add <code>Venice</code> to your <code>Package.swift</code></li>
</ul>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">PackageDescription</span>

<span class="k">let</span> <span class="nv">package</span> <span class="o">=</span> <span class="kt">Package</span><span class="p">(</span>
    <span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span>
        <span class="o">.</span><span class="kt">Package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/Zewo/Venice.git"</span><span class="p">,</span> <span class="nv">majorVersion</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="nv">minor</span><span class="p">:</span> <span class="mi">18</span><span class="p">)</span>
    <span class="p">]</span>
<span class="p">)</span>
</code></pre>
<h1 id='structured-concurrency' class='heading'>Structured Concurrency</h1>

<p>Structured concurrency means that lifetimes of concurrent functions are cleanly nested. If coroutine <code>foo</code> launches coroutine <code>bar</code>, then <code>bar</code> must finish before <code>foo</code> finishes.</p>

<p>This is not structured concurrency:</p>

<p><img src="http://libdill.org/index1.jpeg" alt="not-structured-concurrency" title="Not Structured Concurrency"></p>

<p>This is structured concurrency:</p>

<p><img src="http://libdill.org/index2.jpeg" alt="structured-concurrency" title="Structured Concurrency"></p>

<p>The goal of structured concurrency is to guarantee encapsulation. If the <code>main</code> function calls <code>foo</code>, which in turn launches <code>bar</code> in a concurrent fashion, <code>main</code> will be guaranteed that once <code>foo</code> has finished, there will be no leftover functions still running in the background.</p>

<p>What you end up with is a tree of coroutines rooted in the <code>main</code> function. This tree spreads out towards the smallest worker functions, and you may think of this as a generalization of the call stack — a call tree, if you will. In it, you can walk from any particular function towards the root until you reach the main function:</p>

<p><img src="http://libdill.org/index3.jpeg" alt="call-tree" title="Call Tree"></p>

<p>Venice implements structured concurrency by allowing you to cancel a running coroutine.</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">coroutine</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">Coroutine</span> <span class="p">{</span>
    <span class="k">let</span> <span class="nv">resource</span> <span class="o">=</span> <span class="nf">malloc</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>

    <span class="k">defer</span> <span class="p">{</span>
        <span class="nf">free</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
    <span class="p">}</span>

    <span class="k">while</span> <span class="kc">true</span> <span class="p">{</span>
        <span class="k">try</span> <span class="kt">Coroutine</span><span class="o">.</span><span class="nf">wakeUp</span><span class="p">(</span><span class="mi">100</span><span class="o">.</span><span class="n">milliseconds</span><span class="o">.</span><span class="nf">fromNow</span><span class="p">())</span>
        <span class="nf">print</span><span class="p">(</span><span class="s">"."</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>

<span class="k">try</span> <span class="kt">Coroutine</span><span class="o">.</span><span class="nf">wakeUp</span><span class="p">(</span><span class="mi">1</span><span class="o">.</span><span class="n">second</span><span class="o">.</span><span class="nf">fromNow</span><span class="p">())</span>
<span class="n">coroutine</span><span class="o">.</span><span class="nf">cancel</span><span class="p">()</span>
</code></pre>

<p>When a coroutine is being canceled all coroutine-blocking calls will start to throw <code>VeniceError.canceledCoroutine</code>. On one hand, this forces the function to finish quickly (there&rsquo;s not much you can do without coroutine-blocking functions); on the other hand, it provides an opportunity for cleanup.</p>

<p>In the example above, when <code>coroutine.cancel</code> is called the call to <code>Coroutine.wakeUp</code> inside the coroutine will throw <code>VeniceError.canceledCoroutine</code> and then the <code>defer</code> statement will run, thus releasing the memory allocated for <code>resource</code>.</p>
<h1 id='threads' class='heading'>Threads</h1>

<p>You can use Venice in multi-threaded programs. However, individual threads are strictly separated. You may think of each thread as a separate process.</p>

<p>In particular, a coroutine created in a thread will be executed in that same thread, and it will never migrate to a different one.</p>

<p>In a similar manner, a handle, such as a channel or a coroutine handle, created in one thread cannot be used in a different thread.</p>
<h2 id='license' class='heading'>License</h2>

<p>This project is released under the MIT license. See <a href="LICENSE">LICENSE</a> for details.</p>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2017 <a class="link" href="http://zewo.io" target="_blank" rel="external">Zewo</a>. All rights reserved. (Last updated: 2017-05-20)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.8.1</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</div>
</html>
